Shareware Super Platinum 8/Shareware Super Platinum 8.iso/mac/PROGTOOL/LIB211.ZIP;1/CONTRIB.TXT

Text File | 1993-12-14 | 6.1 KB | 112 lines

                     Standards of the dUFLP Library
                        (written by Jay Parsons)

        The purpose of this library is to assist programmers using the
dBASE language, preferably users of the Borland dBASE products.
Contributions of neat ways to do new things, better ways to do old
things or just handy routines are earnestly requested.  Once accepted,
all such routines are considered placed in the public domain, but
support from the contributor will be appreciated and may be requested.

        In order to make the library as useful as possible, please have
your contributions adhere to the following standards, which are goals
more than rules:

        Modularity - Contributions should be of procedures or functions
that can be used, as far as possible, in any context within the versions
of dBASE for which written.  Where use of external global variables or
files opened before calling the routine is inevitable, the routine
header should specify the required environment.

        Style - Please use the header form, styles of capitalization
and naming of variables and other conventions set forth in DHUNG2.TXT
(now available as part of the dUFLP package). This makes it much easier
for readers of items contributed from different sources to find the
information they need; it may also be required by library-management
programs to assure the inclusion of called routines in files to which
the calling routines are copied.

        Encapsulation - Routines that can reasonably operate without
changing any external variables, active windows, etc., without printing
to the screen, a printer or a file and without changing any dBASE "SET"
items should do so.  ALL VARIABLES CREATED WITHIN A ROUTINE SHOULD BE
"PRIVATE", AND ALL PARAMETERS LEFT UNCHANGED, to keep changes made
within from affecting the outside world.  Any departures from complete
encapsulation, such as opening or closing files, input, output,
changing "SET" items or work areas should be noted in the header. This
does not mean a routine should not change such items, but that if it
does it should restore them to the starting status if it reasonably
can.  This standard is necessarily subjective.  One of the nicer
routines ( CURRPORT() ) in this release is a workaround for the failure
of dBASE IV 1.5 to contain a printerset() function to report what file
or device PRINTER is SET to, without which it cannot be reset on exit.
The workaround routine is complex and slow enough that it may be
preferable simply to note in the header of a routine using printer
redirection that the routine changes the setting, leaving it to users
to add the code needed to detect the original setting and restore it if
it matters to them.

        Error handling - There is generally no need to handle errors
such as calling a routine with the wrong number or type of parameters.
This can be left to the calling program or dBASE itself.  Handling
errors with screen displays of messages, prompts for reentry of data,
etc. is sufficiently complex that this too can usually be left to dBASE
or the calling program. However, in no case should a function return a
value as an error code that might be mistaken for a valid result, such
as 0 for the average of numbers in an array if there are no such numbers
or array.  Something available to the calling routine after the return
should be provided that will, if inspected by the calling routine, give
it notice that an error has occurred.  And, of course, the manner in
which the calling routine should check for an error should be documented
in the header if not obvious.

        Planning ahead - The library contains many fine routines that
are somewhat obsolete.  If contributing one for the future, try to
anticipate changes.  A center() function that takes a string of
characters and prints it in the middle of an 80 x 25 screen is nice, but
one that also takes the width and returns the string padded with blanks
on the left or both ends to the given width is probably better, because
it supports use with screens of other widths or heights, printing the
resulting string to a file and other variations.  This too is
subjective, as anticipating unlikely contingencies will require extra
and slowing code.

        This is your library.  Enjoy it, contribute what you can, and
please report any bugs or other unexpected results to:


Specific Requests:
  1) Use spaces, rather than tabs. If needed, check with Keith Chuvala,
     who has a nifty little routine called TABCVT.EXE that will
     convert your tabs for you. Also, please, for consistency, use
     3 spaces for your indents if at all possible.
  2) Always use the prefix "m->" for your memory variables.
  3) Always end your macros with a dot (¯oname.)
  4) Set your margin to 72 characters maximum for both your documentation
     and your code.
  5) Do not assign a value to a macro as:
     ¯o. = <value>
       The compiler will choke on this. Instead, use:
     store <value> to ¯o.
  6) Please use the header AS SHOWN the end of DHUNG2.TXT included
     with this library.

=======================================================================
NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE

     In order to keep the dUFLP library working in a manner that
     helps the users, we have decided to create four separate
     versions of the library. One will be for dBASE IV, 1.1, one
     for dBASE IV, 1.5, one for dBASE IV, 2.0 and one for dBW. One of
     the reasons for this is to avoid the necessity of keeping
     outdated routines in the later versions of the library. For
     example, in dBASE IV, 1.5, there was no RAT() function, so one
     was created. In dBASE IV, 2.0 there is an internal function
     called RAT(), and therefore there is no need for the external
     (dUFLP) function to be contained in the dUFLP library for dBASE
     IV, 2.0 as well.

     ALL DETAILS ON THIS ARE IN NEWS.TXT
=======================================================================